/**
   \file  algorithm_tester.hh
   \brief Abstract base class defining the interface for different tester
   objects used to exercise the various algorithms in libgist.

   This file defines an ABC that specifies a common interface for the
   different tester objects that will be used to drive the different
   libgist algorithms. The libgist driver program's main function uses an
   object factory to create a tester object for the algorithm named by
   the third command line argument. For example, let's say the user wants
   to test-drive some algorithm "foo" and enters the command:

           gist dataset_name action foo

   The gist driver program will create a foo_driver object by passing the
   argument "foo" to an object factory that churns out objects derived
   from the algorithm_tester class defined in this file. The main program
   can then use this interface object to test-drive the user-specified
   algorithm.
*/

/*
   This file is part of libgist.

   libgist is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the
   Free Software Foundation; either version 2 of the License, or (at your
   option) any later version.

   libgist is distributed in the hope that it will be useful, but WITHOUT
   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
   for more details.

   You should have received a copy of the GNU General Public License
   along with libgist; if not, write to the Free Software Foundation,
   Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
*/

/*
   REVISION HISTORY

   $HeadURL: http://libgist.googlecode.com/svn/branches/lazebnik_dev/drv/algorithm_tester.hh $
   $Id: algorithm_tester.hh 53 2011-09-01 08:09:28Z libgist@gmail.com $
*/

#ifndef GISTDRV_ALGORITHM_TESTER_DOT_HH
#define GISTDRV_ALGORITHM_TESTER_DOT_HH

//------------------------------ HEADERS --------------------------------

// Standard C++
#include <string>

//----------------------- NAMESPACE DEFINITION --------------------------

namespace gistdrv {

//------------------------- CLASS DEFINITION ----------------------------

/**
   \brief Abstract base class defining common interface for different
   tester objects that will drive their respective libgist algorithms.

   libgist provides canned implementations of several different gist
   algorithms but does not attempt to unify the different commands,
   arguments, steps, etc. into a common high-level framework. That task
   falls to the library's clients. This "low-level" approach simplifies
   the implementation of libgist. Additionally, if a client needs only
   one of the algorithms provided by libgist, then it does not have to
   bother with creating an elaborate higher-level interface nor does it
   have to structure its code to conform to whatever high-level interface
   libgist's designers would have come up with.

   However, in some situations (e.g., a driver program for testing all
   the libgist algorithms:), a common interface to the different
   algorithms helps keep the client program's design sane. This class
   (and its subclasses) in conjunction with the action class represents
   one possible way to implement such a common interface to libgist.

   The idea here is to encapsulate the nitty-gritty of each different
   libgist algorithm in its own driver class. For example, an algorithm
   foo will have a foo_driver class that will know how to work with it;
   bar will be encapsulated by bar_driver; so on and so forth. Each of
   these driver classes will be derived from algorithm_tester.
*/
class algorithm_tester {
protected:
   /// A protected constructor because these objects are created by a
   /// factory and cannot be instantiated directly by clients.
   algorithm_tester() ;

public:
   /**
      \brief Collect training images for the algorithm.
      \param cat The category to which the image belongs.
      \param img The name of the file in which the training image is stored.

      This method loads the specified image file and passes it to the
      algorithm requested by the user. Each derived class must implement
      this method and use the API provided by the libgist algorithm it
      encapsulates to effect the training setup action.
   */
   virtual void collect_training_data(const std::string& cat,
                                      const std::string& img) = 0 ;

   /**
      \brief Train the algorithm.

      This method trains the algorithm requested by the user. Each
      derived class must implement this method and use the API provided
      by its particular libgist algorithm to effect the training required
      by the algorithm.
   */
   virtual void train() = 0 ;

   /**
      \brief Save the training results.

      Once an algorithm has been trained, we should save whatever it
      produced as a result of the training process for later use in image
      classification. This method performs the afore-mentioned save
      operation. Each derived class must implement this method and use
      the API provided by the libgist algorithm it encapsulates to effect
      the save training results action.
   */
   virtual void save_training_results() = 0 ;

   /// Clean-up.
   virtual ~algorithm_tester() ;
} ;

//-----------------------------------------------------------------------

} // end of namespace encapsulating this file's definitions

#endif

/* So things look consistent in everyone's emacs... */
/* Local Variables: */
/* indent-tabs-mode: nil */
/* End: */

